Megaware 1

home *** CD-ROM | disk | FTP | other *** search

/ Megaware 1 / Megaware Volume 1.iso / utils / batch-co / powerbat.doc < prev next >

Wrap

Text File | 1991-05-27 | 123.1 KB | 2,675 lines

PowerBatch Version 1.4 COMPUTING SYSTEMS DESIGN, INC. P.O. Box 566484 Atlanta, Georgia 30356-6009 (404) 740-9583 _______ ____|__ | (tm) --| | |------------------- | ____|__ | Association of | | |_| Shareware |__| o | Professionals -----| | |--------------------- |___|___| MEMBER CSD, Inc. is a member of The Association of Shareware Professionals and subscribes to all the policies and standards of this organization. Copyright (c) 1990 by CSD, Inc. All Rights Reserved Worldwide This documentation was produced on May 27, 1991 Table Of Contents Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 1 Registration Fees And What You Get . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 Warranty . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 Distribution Of Compiled Programs . . . . . . . . . . . . . . 6 Software Support . . . . . . . . . . . . . . . . . . . . . . . 6 Concept Of Operation . . . . . . . . . . . . . . . . . . . . . 7 Installation . . . . . . . . . . . . . . . . . . . . . . . . . 9 Constructing A PowerBatch Source File . . . . . . . . . . . . 11 PowerBatch Commands . . . . . . . . . . . . . . . . . . . . . 12 Command Summary . . . . . . . . . . . . . . . . . . . . . . . 40 Compilation Errors . . . . . . . . . . . . . . . . . . . . . . 42 Removing PowerBatch From Your System . . . . . . . . . . . . . 44 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . 45 Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48 Page 1 PowerBatch Page 1 Introduction PowerBatch is a Shareware product. Shareware is a distribution method, not a type of software. With Shareware you get the ultimate money-back guarantee...if you don't use the product, you don't pay for it. Shareware is not free software. Copyright laws apply to both Shareware and commercial software, and the copyright holder retains all rights, with a few specific exceptions as stated in this document. Shareware authors are accomplished programmers, just like commercial authors, and the programs are of comparable quality. (In both cases, you will find good programs and bad ones!) The main difference is in the method of distribution. The author specifically grants the right to copy and distribute the EVALUATION VERSION of the software to anyone as long as no remuneration is received for the distribution of the software unless permission is granted in writing by the author. Shareware distribution gives users a chance to try software before buying it. If you try a Shareware program and continue using it, you are expected to register the software with the author. With registration, you will receive the latest version of the software without the evaluation titles and messages. With shareware you are able to try the software on your computer with your own set of peripherals, the only way to know if it will function in your own environment. After deciding that PowerBatch is a software product that you will use, then and only then do you pay for it. The ultimate trust from the author! When you do pay for the software, you pay only for the software, not for advertisement for the software which can cost many times what the software actually costs. CSD, Inc. is a member of the Association of Shareware Professionals (ASP). ASP wants to make sure that the shareware principle works for you. If you are unable to resolve a shareware-related problem with an ASP member by contacting the member directly, ASP may be able to help. The ASP Ombudsman can help you resolve a dispute or problem with an ASP member, but does not provide technical support for members' products. Please write to the ASP Ombudsman at P.O. Box 5786, Bellevue, WA 98006 or send a Compuserve message via easyplex to ASP Ombudsman 70007,3536. While CSD has no immediate plans to move, businesses do move from time to time. Since shareware tends to remain on some bulletin boards without update for many years, if the shareware author does move, you may experience a problem in contacting the author. You may also contact ASP to learn of the current address of any ASP member if you experience this problem. Page 2 PowerBatch Page 2 Trademarks PowerBatch is a trademark of Computing Systems Design, Inc. MS-DOS is a trademark of Microsoft Corporation. IBM and PC-DOS are trademarks of IBM Corporation. ASP, Association of Shareware Professionals, and the ASP logo are registered trademarks of the Association of Shareware Professionals. License Agreement This file contains important license information regarding the use of PowerBatch. This information applies to individual users who wish to pass copies out to friends and associates. User Groups, Computer Clubs, Disk Vendors and Distributors, subscription Services, Disk-of-the-Month Clubs, etc., should refer to the VENDOR.DOC file for complete information relating to them. BBS SYSOPs should refer to the SYSOP.DOC file for complete information relating to them. Trial Use License PowerBatch is NOT a public domain program. It is Copyright 1990, 1991 by Computing Systems Design, Inc. (CSD, Inc.). All rights reserved. This software and accompanying documentation are protected by United States Copyright law and also by International Treaty provisions. Any use of this software in violation of Copyright law or the terms of this limited license will be prosecuted to the best of our ability. The conditions under which you may copy this software and documentation are clearly outlined below under "Distribution Restrictions". Computing Systems Design, Inc. (CSD, Inc.) hereby grants you a limited license to use this software for evaluation purposes for a period not to exceed thirty (30) days. If you intend to continue using this software (and/or it's documentation) after the thirty (30) day evaluation period, you MUST make a registration payment to Computing Systems Design, Inc. (CSD, Inc.). Using this software after the thirty (30) day evaluation period, without registering the software is a violation of the terms of this limited license. Page 3 PowerBatch Page 3 Licensee shall not use, copy, rent, lease, sell, modify, decompile, disassemble, otherwise reverse engineer, or transfer the licensed program except as provided in this agreement. Any such unauthorized use shall result in immediate and automatic termination of this license. All rights not expressly granted here are reserved to Computing Systems Design, Inc. (CSD, Inc.). Limited Distribution License As the copyright holder for PowerBatch, Computing Systems Design, Inc. (CSD, Inc.) authorizes distribution by individuals only in accordance with the following restrictions. (User Groups, Computer Clubs, Disk Vendors and Distributors, Subscription Services, Disk-of-the-Month Clubs, etc., should refer to the VENDOR.DOC file for complete information relating to them.) (BBS SYSOPs should refer to the SYSOP.DOC file for complete information relating to them.) Individuals are hereby granted permission by Computing Systems Design, Inc. (CSD, Inc.) to copy the PowerBatch diskette for their own use (for evaluation purposes) or for other individuals to evaluate, ONLY when the following conditions are met. The PowerBatch package is defined as containing all the material listed in the PACKING.LST text file. If any files listed in the PACKING.LST text file, or the PACKING.LST file itself, are missing, then the package is not complete and distribution is forbidden. Please contact CSD, Inc. to obtain a complete package suitable for distribution. o The PowerBatch package - including all related program files and documentation files -CANNOT be modified in any way and must be distributed as a complete package, without exception. The PACKING.LST text file contains a list of all files that are part of the PowerBatch package. o No price or other compensation may be charged for the PowerBatch package. A distribution cost may be charged for the cost of the diskette, shipping and handling, as long as the total (per disk) does not exceed US$8.00 in the U.S. and Canada, or US$12.00 internationally. Page 4 PowerBatch Page 4 o The PRINTED User's Guide may not be reproduced in whole or in part, using any means, without the written permission of Computing Systems Design, Inc. (CSD, Inc.). In other words, the disk-based documentation may not be distributed in PRINTED (hardcopy) form. o The PowerBatch package cannot be "rented" or "leased" to others. o The person receiving a copy of the PowerBatch package MUST be made aware that each disk or copy is ONLY for evaluation, and that Computing Systems Design, Inc. (CSD, Inc.) has not received any royalties or payment for the product. This requirement can be met by including the complete PowerBatch package, which contains any appropriate registration information. o The person receiving a copy of the PowerBatch package MUST be made aware that he or she does not become a registered user until Computing Systems Design, Inc. (CSD, Inc.) has received payment for registration of the software. This requirement can be met by including the complete PowerBatch package, which contains any appropriate registration information. o Computing Systems Design, Inc. (CSD, Inc.) prohibits the distribution of outdated versions of the PowerBatch package, without written permission from Computing Systems Design, Inc. (CSD, Inc.). If the version you have is over twelve (12) months old, please contact us to ensure that you have the most current version. This version of PowerBatch was released May 27, 1991. o Licensee shall not use, copy, rent, lease, sell, modify, decompile, disassemble, otherwise reverse engineer, or transfer the licensed program except as provided in this agreement. Any such unauthorized use shall result in immediate and automatic termination of this license. o U.S. Government Information: Use, duplication, or disclosure by the U.S. Government of the computer software and documentation in this package shall be subject to the restricted rights applicable to commercial computer software as set forth in subdivision (b)(3)(ii) of the Rights in Technical Data and Computer Software clause at 252.227-7013 (DFARS 52.227-7013). The Contractor/manufacturer is Computing Systems Design, Inc., P.O. Box 566484, Atlanta, GA 30356-6009. All rights not expressly granted here are reserved to Computing Systems Design, Inc. (CSD, Inc.). Page 5 PowerBatch Page 5 Commercial users (every user except individual users) of PowerBatch must register and pay for their copies of PowerBatch within 30 days of first use or their license is withdrawn. Site- License and/or dealer arrangements may be made by contacting Computing Systems Design, Inc. (CSD, Inc.). See Appendix A for Dealer and Site License prices. Anyone distributing PowerBatch for any kind of remuneration must first contact Computing Systems Design, Inc. (CSD, Inc.) at the address on the title page for authorization. This authorization will be automatically granted to distributors recognized by the (ASP) as adhering to its guidelines for shareware distributors, and such distributors may begin offering PowerBatch immediately (However Computing Systems Design, Inc. (CSD, Inc.) must still be advised so that the distributor can be kept up-to-date with the latest version of PowerBatch.). To register your copy of PowerBatch, print the file REGISTER.FRM, complete this form, and send along with your registration fee to CSD, Inc. You will receive the latest version of the program along with the latest documentation. The fully registered version of the program removes all references to evaluation. Registered users will receive notice of all updates made to the program and these updates will be supplied to registered users for a nominal charge. Every effort will be made to supply updates to registered users at the lowest possible cost. If you need to submit an invoice to your accounts payable department, print the form INVOICE.FRM and fill in the appropriate blanks. Registration Fees And What You Get The evaluation version of PowerBatch contains 100% of the capabilities of the registered version. Those who register PowerBatch will receive the latest release of the software and documentation and will receive update offers in the mail at a minimal cost as they become available. CSD maintains copies of innovative batch files submitted by users and will include the best of these batch files along with the registered software. The registration fee for PowerBatch is US $30. Price is subject to change without notice but will be guaranteed through December 1990. If payment is by check, these funds must be drawn on a US bank. Unfortunately the processing of non-US checks can be as much as $20 and we cannot afford this type of transaction. We are continually looking for innovative ways to serve non-US customers. Page 6 PowerBatch Page 6 Warranty TRIAL USE (SHAREWARE EVALUATION VERSION) WARRANTY: The Shareware evaluation (trial use) version is provided AS IS. Computing Systems Design, Inc. MAKES NO WARRANTY OF ANY KIND, EXPRESSED OR IMPLIED, INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A PARTICULAR PURPOSE. REGISTERED VERSION ONLY WARRANTY: Computing Systems Design, Inc. warrants the physical diskette(s) and physical documentation provided with registered versions to be free of defects in materials and workmanship for a period of sixty days from the date of registration. If Computing Systems Design, Inc. receives notification within the warranty period of defects in materials or workmanship, and such notification is determined by Computing Systems Design, Inc. to be correct, Computing Systems Design, Inc. will replace the defective diskette(s) or documentation. The entire and exclusive liability and remedy for breach of this Limited Warranty shall be limited to replacement of defective diskette(s) or documentation and shall not include or extend to any claim for or right to recover any other damages, including but not limited to, loss of profit, data, or use of the software, or special, incidental, or consequential damages or other similar claims, even if Computing Systems Design, Inc. has been specifically advised of the possibility of such damages. In no event will Computing Systems Design, Inc.'s liability for any damages to you or any other person ever exceed the lower of suggested list price or actual price paid for the license to use the software, regardless of any form of the claim. Computing Systems Design, Inc. SPECIFICALLY DISCLAIMS ALL OTHER WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, ANY IMPLIED WARRANTY OF MERCHANTABILITY AND/OR FITNESS FOR A PARTICULAR PURPOSE. Distribution Of Compiled Programs REGISTERED USERS of PowerBatch may distribute the compiled output from any PowerBatch program written by the registered user without any fees to CSD, Inc. CSD recognizes that the source and compiled output are original works of the author and that PowerBatch was a tool used in the process of creating the .EXE file. Page 7 PowerBatch Page 7 Software Support Support for PowerBatch may be obtained by contacting CSD,Inc. on Compuserve using Compuserve Mail (EasyPlex). Address inquiries to Compuserve ID 72701,155. If you are not a Compuserve member, you may obtain support by writing to: Computing Systems Design, Inc. P.O. Box 566484 Atlanta, Georgia 30356-6009 If you feel you have a question that needs immediate attention and you are a registered user, CSD's office hours are 8AM until 5PM CST. We will be happy to discuss any problems or suggestions for PowerBatch but time does not permit us to help you debug your PowerBatch source problems. Page 8 PowerBatch Page 8 Concept Of Operation PowerBatch is a compiler for batch file "type" commands. At the present time there are over 40 PowerBatch commands which will work only in a PowerBatch source file (they will not execute in a standard DOS batch file). Any valid executable command (.EXE & .COM) as well as any of the DOS intrinsic commands are valid within a PowerBatch source file and will be "compiled". These .EXE, .COM and DOS intrinsic commands will be executed via a shell and the PowerBatch .EXE program will continue execution with the next compiled statement following the shelled command. There are two main modules supplied with PowerBatch; 1)POWERMAK.EXE and 2)SMLMODEL.MDL. PowerMak reads, parses the source file, and compiles the source extracting routines from SmlModel. The result is a completely standalone .EXE file that executes without SmlModel or PowerMak. The increase in speed comes from the use of the PowerBatch commands as the DOS and executable modules will not be executed any faster. Most notable is the increase in speed dealing with screen writes. Many capabilities are provided in PowerBatch commands that simply are not available with standard DOS commands. Why Use PowerBatch There are four major reasons for using a compiled PowerBatch program: 1) The resulting program will almost certainly execute considerably faster. While it might be possible to construct a compiled PowerBatch program that does not execute faster, it would have to consist entirely of pre- existing executable modules. 2) PowerBatch commands provide a considerable increase in flexibility and power over conventional batch files. 3) PowerBatch programs cannot be changed without making machine code modifications. This means additional security for distributed batch files. 4) PowerBatch programs can be created quickly for the PowerBatch command set is a very high level language. PowerBatch commands fall into 5 classes of commands; 1) Commands which provide systems information. These commands provide the current color settings, the current date, the current time, check for the existence of a valid drive letter, and commands which check for the existence of a directory or a file. 2) Commands which control the flow of the batch program. Execute different portions of the batch program based on existence or non-existence of directories or files. Compare the contents of one variable with the contents of another variable or a constant and execute different portions of the Page 9 PowerBatch Page 9 batch program based on the results of the compare. 3) Commands which control the way text is printed on the screen. Change any portion of the screen to any valid screen color, cause a message to blink on the screen, or highlight a message in reverse video. 4) Commands which provide string manipulation. Change a string to all upper case characters, or all lower case characters. Extract a portion of a string such as the first three characters or the last four characters. Build a new string from two existing strings by concatenation of the two strings. 5) Commands which deal with screen writing and input from the keyboard. These commands are the main power in the PowerBatch system. Directly address any position on the screen and move the cursor to that position to read or write text. Automatically center a message or title on any line. Draw boxes around portions of the screen to enhance screen appearance. Read a single key from the keyboard, read the response to a query that only accepts a yes or no response, read a string of characters from the keyboard with a specified maximum length, and read keys from the keyboard automatically changing the characters to upper case. Page 10 PowerBatch Page 10 Installation Installation is accomplished by executing the PBInstal program. It seemed only fitting that this install program be a compiled PowerBatch program. I believe this to be the epitome of self- installing software. The two main modules POWERMAK.EXE and SMLMODEL.MDL must be located in the DOS path to allow you to compile PowerBatch programs from any directory on your system. PowerBatch may be run on a system as small as a single floppy drive system with 128K. There will be some limit to the number of source statements that may be compiled on a system this small as memory is dynamically allocated as compilation progresses. A source file of several hundred statements can be compiled on a small machine. The PBInstal program is strickly a file copy program. It will ask you where you wish to place the PowerBatch files and copy them to the specified directory. You may copy your own files to various directories if you desire. You may even copy POWERMAK.EXE and SMLMODEL.MDL to a directory not on your path if you desire. If you do so, you may compile only from the directory containing these two files. PowerBatch may be installed from either drive A, B, or a hard drive. If the PowerBatch source is on a floppy disk, you may execute the install procedure by: 1) If your current drive is the A: (or B:) drive then enter PBInstal <enter>. 2) If you current drive is other than A: (or B:) then enter A:PBInstal <enter> (or B:PBInstal <enter>). If you are installing PowerBatch from a fixed disk drive such as C:, then make the directory which contains the PowerBatch source the current default directory. For example if you have the PowerBatch source in a directory named C:\TEMP, then at a DOS prompt enter CD \TEMP <enter> PBInstal <enter> You will first be asked to enter the directory name which contains the PowerBatch source. Next you will be asked to enter a directory name on your DOS path where the PowerBatch compiler will be placed. POWERMAK.EXE and SMLMODEL.MDL will be placed in this directory. Before you begin the installation process, know the name of a directory which is on the DOS search path where you will place these two files. The install program will not allow you to place the compiler in a directory that is not on the search path. Page 11 PowerBatch Page 11 Now you will be asked to enter a directory name where you would like the documentation, informational, and example files to be placed. This directory does not have to be on your DOS path. If this directory does not exist, PowerBatch will create this directory for you if you desire. The documentation and information files will be placed in this directory. The first time that you run the PowerBatch compiler, it will customize itself for the computer on which you are running. This process takes about a minute and will not run again. Take this opportunity to learn about the shareware distribution process and how to register PowerBatch if after taking it for a test drive, you feel you would like to add it to your collection of utilities. We at CSD would like to share innovative batch file creations with our customer base. If you have created such a PowerBatch program and would like to share it with other PowerBatch users, send it to us and if we agree with you we will include it on our registration disk to our customers. You may mail us a disk containing the PowerBatch source or you may send it via CompuServe EasyPlex. Our address is: CSD, Inc. P.O. Box 566484 Atlanta, GA 30356-6009 Our CompuServe ID is 72701,155. Page 12 PowerBatch Page 12 Constructing A PowerBatch Source File Use your favorite text editor to create a printable ascii file containing PowerBatch source commands and DOS executable commands. A printable ascii file is one that may be typed to the screen (ie type myfile.pwr <enter>) and the results printed on the screen contain only the file contents. Most files created with a word processor are not printable ascii files unless you specify an ascii file output option. Compile your source statements to create a .EXE executable module. This is done using the POWERMAK compiler. The syntax is: POWERMAK MyFile [OutFile] [+M] PowerMake assumes the extension of the input file to be .PWR (ie MYFILE.PWR) and will create an output file of MYFILE.EXE if no OutFile parameter is specified. The input source file may be any DOS name of your choice(including the extension). You may also specify an output file name of your choice but the extension will always be .EXE. If you do not enter the input file name on the command line, the program will prompt you for the name. You must at this time enter the complete name including the extension. If you wish to generate a list of all literals, variables, and labels used in your PowerBatch program, add +M to the end of the command line. This variable map will be written to the POWERBAT.ERR file. If you will be running the output from the compilation on any computer that is operating under a version of DOS that is earlier than DOS version 3.0, you must enter the compiler directive +D2. This directive will cause the compilation to be much slower but the resulting .EXE file will execute on computers running on DOS 3.0 and up at the SAME SPEED as compilations made without the +D2 directive. If in doubt, use +D2. A minute of compile time will eliminate future problems. If the compiler finds no compilation errors, the compiled version of your source file will be generated. For an explanation of compilation errors, see the section entitled "Compilation Errors". Compilation errors appear on your screen as they are encountered and they are written to a file named POWERBAT.ERR. The entire source code is scanned each time you compile a PowerBatch program (ie the compiler does not stop when an error is found, but attempts to identify all errors on each pass). This means that some errors will be the result of previous errors found in the source. If there are no compilation errors, the POWERBAT.ERR file will not be created. Page 13 PowerBatch Page 13 PowerBatch Commands Commands, Variable Names, and Labels are not case sensitive. Everything on the command source line is converted to upper case except a literal which is enclosed within quotes. Either single quotes(') or double quotes(") may be used to denote a literal. Literals which are numeric such as color values, variable lengths, etc. should not be enclosed in quotes. The compiler does evaluate each literal (both alpha and numeric) in the same manner. The evaluation process is 1) remove leading and trailing quotes if any, 2) attempt to convert literal to numeric, 3) if numeric conversion is successful, consider it a number, 4) if numeric conversion is unsuccessful, consider it alpha numeric. This means that internally an operand of 3 and "3" will both be numeric. A semicolon which is not enclosed within quotes or a part of a command is used to denote a comment. Semicolons which are part of a command must not be preceded by a space. A comment begins with a semicolon which follows a space not within quotes. Comments may appear anywhere on the command line, but everything after a semicolon on a command line is ignored. A comment may begin in column 1 by placing the semicolon in column 1. The following are NOT comments: path=d:\;c:\util;c:\wp path "d:\;c:\util;c:\wp" WriteLine "Punctuation may be used within quotes;" These ARE comments: Variable ColorSave,3 ;save the original color SetVar Msg, ErrMsg ;set Msg to "Invalid input; re-enter" The starting location on the command line of the command and the operands is not important and tabs and spaces may be freely used for readability. Variable names and command labels may be any length in the source command but are significant only through the first eight positions. Variables, Literals, and Labels A variable is a location in memory that you allocate and give a name and a maximum length. Anytime you refer to the "name" of the variable, you are referencing the memory locations set aside for this variable. Variable names give you an easy way to manipulate data internally within the computer. The following are examples of variables: Page 14 PowerBatch Page 14 Variable CharIn,1 This variable gives the name "CharIn" to one memory position. It will be used to hold one character responses from the keyboard by the user. Variable PBDir,79 This variable appears in the PBInstal program and holds the name of the directory where the PowerBatch compiler will be placed. It is composed of the drive letter and directory entered by the user in response to two questions during the installation process. Variable CompName,35,"The ABC Company" This variable reserves 35 positions in memory and gives these locations the name CompName. The PowerBatch compiler also places the initial value "The ABC Company" in the first 15 positions of the variable. The value of this variable may be changed by later processing in the program. When this variable is referenced in the program it will contain only 15 characters (The ABC Company) with no leading or trailing spaces, assuming the program has not assigned a new value. Variable MsgClear,20," " This variable contains 20 spaces and is named MsgClear. It will be used to "clear" or overwrite with spaces an error message in your program. Once you have displayed a message to the user, it should be cleared as you continue with the program. This is done by overwriting with spaces. Having a variable with the correct number of spaces makes this task easier. There are two predefined variables in each PowerBatch program; ERRORLEVEL and DOSERROR. The ErrorLevel variable and the DOSError variable are updated each time an EXTERNAL COMMAND is executed. If you execute a program which sets an error code on exit, this error code will be in ERRORLEVEL. The use of ERRORLEVEL in PowerBatch is equivalent to the use of ERRORLEVEL in a standard DOS batch file. If you execute an external command(program) and that command does not terminate normally, the variable DOSERROR will be set to the DOS error code assigned by the operating system IF A DOS ERROR CODE WAS GENERATED BY THE OPERATING SYSTEM. It is good practice to examine the DOSERROR variable after executing an external command. Literals are very much like variables which have a value but no name. Literals are used in PowerBatch commands when you wish to pass an actual value to the command instead of a variable. Note in the following examples that literals containing numbers only are not enclosed in quotes and literals containing any non- numeric characters are enclosed in quotes. If you specify a number as a literal either convention is acceptable (3 or "3"). Page 15 PowerBatch Page 15 If you specify alphabetic characters, the quotes are required. For readability, and ease of entry, numeric literals usually do not contain quotes. Examine the following examples of literals: Center "Installation Program",1 This command will center the literal "Installation Program" on line 1 of the screen. The text "Installation Program" must appear somewhere in the program and it appears as a literal. It will occupy memory positions and will have a value but you may not reference this value by name. By instructing the compiler to write this literal, the compiler automatically creates the memory locations and initial value but gives it no name. The 1 is also a literal in this command. Each time you use a literal in a PowerBatch program, the previously assigned literals are checked for duplication and if the literal has been previously assigned, the prior assignment will be used (ie literal values will appear only one time regardless of the number of times used). WriteAt 12,3,Msg1 There are two literals in this command. The numbers 12 and 3 are both created as literals. In this command they specify the column and row location where the string Msg1 will be written. Again, the compiler creates the memory locations and values for these literals, but no names. If you were to write another command such as the Beep command which specifies that the system speaker will beep at a certain frequency for 3 times, the compiler will find the previously defined literal "3" and use this value instead of creating another literal. Beep ErrTone,8,3 This is the Beep command referenced in the previous example. The beep command will cause the speaker to sound at a frequency of ErrTone for .8 second and repeat 3 times. The "3" literal will use the same memory location reference as the WriteAt command used in the previous command (ie another literal will not be created). Labels are names of a particular place in your PowerBatch program that you will go to without executing the previous command. You go directly to this location in the program from another location in the program based on a decision you have made in the program. Examples will help explain: ReadYN "Do you wish to continue [Y/N] ",InChar Compare InChar,"Y",,,GetDrive Halt 999 ;end the program if user enters "N" Label GetDrive Page 16 PowerBatch Page 16 This group of commands writes the message on the screen and asks the user to input either Y or N (the command will only accept these two characters). A comparison is then made to a literal "Y" and the compare command will jump to the location in the program named GetDrive if a "Y" was entered or will execute the next command if "N" was entered. GoTo NextCmd . . . Label NextCmd In this most straightforward use of the label, the user simply uses the GoTo command and jumps unconditionally to another point in the program. External commands are entered just as PowerBatch commands are entered. If you enter an external command and this command uses command line parameters, these parameters may be passed as either variables or literals. Remember that if the parameter is not numeric, it must be enclosed in quotes or it will be treated as a variable. Any PowerBatch statement which is an external command may contain a maximum of 7 command line variables. That is not to say that you may not pass more than 7 command line parameters to an external program but that these command line variables may not be contained in more that 7 PowerBatch variables. For example: Variable Parm1,5,"one" Variable Parm2,5,"two" Variable Parm3,5,"three" Variable Parm4,5,"four" Variable Parm5,5,"five" Variable Parm6,5,"six" Variable Parm7,5,"seven" Variable Parm8,5,"eight" Variable BigParm,80 ;ExtPgm will have the last parm truncated ExtPgm Parm1,Parm2,Parm3,Parm4,Parm5,Parm6,Parm7,Parm8 ;valid method for passing these parms (1 PowerBatch parm) Extpgm "one two three four five six seven eight" ;accomplishing the same thing with variables (6 PowerBatch parms) Concat BigParm,Parm1," " Concat BigParm,Parm2 Concat BigParm," " Concat BigParm,Parm3 ExtPgm BigParm,Parm4,Parm5,Parm6,Parm7,Parm8 Examples of external programs as PowerBatch commands: Page 17 PowerBatch Page 17 Variable InChar,1 ReadYN "Do you wish a directory ",InChar Compare InChar,"Y",NextSec,NextSec DIR "/W" SETUP "> null" ;printer redirection Variable PgmName,12 Write "Enter the name of the program to compile " ReadStr PgmName TPC PgmName, "/ddebug" This third example of external commands show the use of the two predefined variables, ERRORLEVEL and DOSERROR. After the execution of "TestPgm", we examine DOSError to find if the program executed OK (Possibly there was not enough memory or the program could not be found on the DOS path). After determining that the program executed OK, we examine the exit code set by "TestPgm" to determine the flow of the remainder of our batch file. This exit code will be found in the variable ERRORLEVEL. Variable MsgLine,80 . . TestPgm "Parm1 Parm2" Compare DOSError,0,,,RanOK WriteLine "TestPgm did not execute properly...terminating" Halt DOSError Label RanOK Compare ErrorLevel,1,Chk2,,Option1 Concat MsgLine,"Unexpected return code of ",ErrorLevel Halt Label Option1 Note: PowerBatch programs may be executed by other PowerBatch programs as external commands. An option of the PowerBatch Halt command is to set the DOS errorlevel. You could then "pass parameters" from one PowerBatch program to another via the ERRORLEVEL variable. Page 18 PowerBatch Page 18 Command line parameters may be passed to a compiled PowerBatch program. These command line parameters must be defined at compile time and have special variable names. Up to 16 parameters may be passed to a PowerBatch program and their names are CLP%1 - CLP%16. If you wish to pass parameters on the command line to your PowerBatch program, define the command line parameter variables (CLP%1 - CLP%16) in your PowerBatch source prior to compilation and when you run the compiled program, any parameters entered on the command line will be in the defined variable. Example: Source for SMARTCPY.PWR Variable CLP%1,79 ;source file Variable CLP%2,79 ;target file Variable InChar,1 ReadYN "Shall I copy the files for you [Y/N] ",InChar Compare InChar,"Y",NoCopy,NoCopy COPY CLP%1, CLP%2 SMARTCPY FILE1 FILE2 will execute the DOS copy command and copy FILE1 to FILE2 if the user responds Y to the question. Changes To Your Computer's Environment Area Your computer memory contains a special area of memory called the "Environment Area". This special area of memory contains the values assigned to variables that are available to the DOS operating system or to any application program running in your computer. These values remain unchanged until DOS or an application program changes them as long as the power is on to your computer. DOS maintains special values in this area which the operating system uses. Your current path and current prompt configuration are two of these values. These values are normally set with the DOS PROMPT or PATH command. If an application program like a compiled PowerBatch program executes a DOS command, it is done via a "shell" or another copy of your command processor (normally COMMAND.COM) which is started to handle the execution of these DOS commands. When a shell is started, DOS creates a copy of the environment area for this new shell and makes the environment values available to the shell. Unfortunately, when the shell is terminated (when the DOS command is complete) this copy of the environment is erased from memory. If you execute a PROMPT, PATH or SET [Variable] command, the copy of the environment created for the shell to run the PROMPT, PATH, or SET command is updated and immediately erased when the PowerBatch program is finished. PowerBatch however, provides you a means to update both the permanent copy and the current copy of the environment area with the commands SETPATH, SETENV, and PROMPT. Unfortunately, problems dealing with the environment area do not Page 19 PowerBatch Page 19 end here. When DOS runs a program (like a PowerBatch compiled program), a copy of the permanent environment is made and is the "active" environment area in use during the running of the program. If you only read the values of existing environment variables, there is no problem. If you attempt to add new environment values, the amount of free environment space is very limited. IT IS NOT THE AMOUNT OF SPACE ALLOCATED BY YOU IN YOUR CONFIG.SYS FILE (or the default) MINUS THE AMOUNT OF USED SPACE! The amount of "free" space appears to be only the amount left after rounding up the amount of used space to the nearest paragraph of memory (16 bytes). The problem of allocating environment free space can be circumvented by updating the permanent environment area with dummy values prior to the execution of your PowerBatch file. This could be done with a small PowerBatch program such as ENV- INIT.PWR as follows: SetEnv Env1,'dummy value dummy value' SetEnv Env2,'dummy value dummy value' . . . When ENV-INIT terminates, the environment variables Env1 and Env2 will have the dummy values and will now be a part of any environment area copy passed to a running program. You could of course use the DOS SET command from the DOS command line or initialize the environment variables with dummy values in your AUTOEXEC.BAT file. Command Notation In the description of the commands which follow, that which appears within brackets [ ] is optional and all other operands are required. Any time a screen color may be specified in a command such as CLEARLINE LineNumber,ForegroundColor,BackgroundColor the single attribute which is used in many color conventions may be substituted for the pair of color attributes. For example, foreground color 4 (red), background color 1 (blue), is identical to color attribute 20 and the CLEARLINE command may be specified EITHER as CLEARLINE 14,4,1 or CLEARLINE 14,20 to clear line 14 on the screen to red foreground on blue background. For this reason anytime that the operand pair of foreground color, background color is required, the single color attribute may be substituted for the pair. The compiler will not detect missing background color attributes but will assume that Page 20 PowerBatch Page 20 the foreground is the composite value. How do I calculate this color attribute? The composite color attribute is the operating systems shorthand method of keeping both the foreground and background colors in one byte of memory. It may be calculated by multiplying the background color by 16 and adding the foreground color. See Appendix B for a complete list of composite color attributes. Color Attribute = (Background X 16) + Foreground RedOnBlue = (1 X 16) + 4 = 20 WhiteOnBlack = (0 X 16) + 7 = 7 YellowOnRed = (4 X 16) + 14 = 78 This uses the ascii values 0 through 127 for all the colors available. To make any color blink, add 128 to the color value. YellowOnRed,Blinking = 78 + 128 = 206. Command Syntax Several examples are available on the distribution disk. All source code examples have a file extension of .PWR. These examples may be edited with your favorite text editor and printed by "copying" the file to the printer such as COPY PBINSTAL.PWR LPT1. ================================================== ?COLOR VarName1, VarName2, VarName3 Retrieve the current color attributes from the system and place the current foreground color in VarName1, the current background color in VarName2, and the composite attribute in VarName3. See Appendix B for complete list of composite color attributes. Ex: Variable ForeColor,3 Variable BackColor,3 Variable ColorAttr,3 ?Color ForeColor,BackColor,ColorAttr Retrieve the current foreground, background and composite color values and place in the variables ForeColor, BackColor, and ColorAttr respectively. To create professional batch files it is a good idea to retrieve the current color setting as the first command in the program and reset these values and clear the screen at the end of your program. This restores the users computer to the same color state that you found when your PowerBatch program was executed. ================================================== Page 21 PowerBatch Page 21 ?CURRDIR VarName1, VarName2 Retrieve the current drive and directory from the system and place the current drive in VarName1 and the current directory in VarName2. The contents of VarName1 prior to execution of this command control which currently logged drive is searched for the currently logged directory. If ?CurrDir finds a valid drive letter in the first position of VarName1, then the contents of VarName2 will be the currently logged directory of that drive. If the first position of VarName1 does not contain a valid drive letter, then VarName2 will contain the currently logged directory of the current drive. In either case VarName1 will contain the drive and VarName2 will contain the directory. Ex: Variable CurrDrive,2 Variable CurrDir,79 SetVar CurrDrive,"A" ?CurrDir CurrDrive,CurrDir SetVar CurrDrive,"" ?CurrDir CurrDrive,CurrDir In the first usage of ?CurrDir, assuming that the currently logged directory on the A drive is the root directory, CurrDrive will contain "A" and CurrDir will contain "\" after the execution of ?CurrDir. In the second usage, assuming that the currently logged drive is D: and the currently logged directory on the D: drive is "\UTIL\EXEC", CurrDrive will contain "D" and CurrDir will contain "\UTIL\EXEC" after the execution of ?CurrDir. ================================================== ?DATE VarName1, VarName2, VarName3, VarName4 Retrieve the current date from the system and place the day of the week in VarName1, the month in VarName2, the day in VarName3, and the year in VarName4. VarName1 should be defined as 9 long, VarName2 and VarName3 as 2 long, and VarName4 as 4 long. Ex: Variable DOW,9 Variable Mo,2 Variable Da,2 Variable Yr,4 ?Date DOW,Mo,Da,Yr Retrieve the current date and place the component parts in their respective variables. Place the day of the week in DOW (ie Saturday), the month number in Mo (ie 06), the day of the month in Da (ie 29), and the year in Yr (ie 1990). Page 22 PowerBatch Page 22 ================================================== ?DIREXIST VarName1, Label1 [,Label2] Literal1,Label1 [,Label2] Check the system for the existence of the directory whose name appears in VarName1 or in Literal1. If the directory exists jump to the command immediately following Label1, if the directory does not exist, jump to the command immediately following Label2. Ex: ?DirExist InpStr,DirOk,BadDir ?DirExist "C:\",DirOK,BadDir ?DirExist InpStr,,BadDir (next command if exists) ?DirExist InpStr,DirOk (next command if not exist) In the first example if the contents of the variable InpStr exists then goto label DirOK, if it does not exist go to the label BadDir. In the second example we check for the existence of a literal with a value of "C:\". In the third example, if the contents of InpStr exist we "fall through" to the next instruction, if the directory does not exist we jump to the label BadDir. In the fourth example, if the directory name in InpStr exists, we jump to the label DirOK, if it does not exist we fall through to the next command. ================================================== ?DISKSPACE VarName1, VarName2, VarName3 Literal1, VarName1, VarName2 Query the disk Drive specified by the first character of Varname1 and place the total disk capacity in bytes in VarName2 and the unused bytes in VarName3. Since the command looks at only the first character of VarName1 (or Literal1), VarName1 may contains strings such as "C:\UTIL". Ex: Variable DirName,79 ReadStr DirName (user enters "c:\util") Upper DirName (changes to "C:\UTIL") ?DiskSpace DirName,TotSpace,FreSpace This will place the total capacity of drive C: in the variable TotSpace and the amount of this space that is unused in the variable FreSpace. ?DiskSpace "A",TotSpace,FreSpace This accomplishes the same task using a literal of "A". Page 23 PowerBatch Page 23 ================================================== ?DRIVEEXIST VarName1, Label1 [,Label2] Literal1, Label1 [,Label2] Check the system for VarName1 as a valid drive letter. If the drive is valid, jump to the command immediately following Label1, if the drive is not valid jump to the command immediately following Label2. Ex: ?DriveExist DrvNum,GoodDrv,BadDrv ?DriveExist "A",GoodDrv,BadDrv ?DriveExist DrvNum,,BadDrv ?DriveExist DrvNum,GoodDrv ================================================== ?ENVSTR VarName1, VarName2 Literal1, VarName2 Retrieve the contents of any environment variable from the system environment area. The name of the environment variable is placed in VarName1 or entered as a literal and the contents of the environment variable will be placed in VarName2. Ensure that VarName2 has been defined sufficiently long enough to contain the contents of the environment variable. If VarName2 is not long enough, the environment variable will be truncated. To display the currently defined environment variables, use the DOS "SET" command at a DOS prompt. (ie C:>SET <enter>) You should receive at least two environment variables (assuming you have set a path) with the format NAME=VALUE. The location of your command processor is in an environment variable named COMSPEC and should look something like this: COMSPEC=C:\COMMAND.COM. Ex: Variable EnvValue,255 Variable EnvName,4,"path" ?EnvStr "prompt", EnvValue ?EnvStr EnvName, EnvValue ================================================== Page 24 PowerBatch Page 24 ?FILEEXIST VarName1, Label1 [,Label2] Literal, Label1 [,Label2] Check the system for the specified file name. If the file exists, jump to the command immediately following Label1, if the file does not exist, jump to the command immediately following Label2. Ex: ?FileExist FileName, Label1, Label2 ?FileExist "C:\AUTOEXEC.BAT",StartOK,NoStart ?FileExist FileName,,Label2 ?FileExist FileName,Label1 ================================================== ?INPATH VarName1, Label1 [,Label2] Literal1, Label2 [,Label2] Compare the contents of VarName1 to the system search path. If VarName1 is contained within the path jump to the command immediately following Label1, if the file does not exist jump to the command immediately following Label2. Use this command to determine if a directory is specified in the DOS search path. Ex: DOS search path contains "C:\UTIL;C:\WORDPROC;D:\" Variable InString,79 Write "Enter your directory name " ReadStr InString (user enters "c:\wordproc") Upper InString (change to "C:\WORDPROC") ?InPath InString,PathOK,BadPath ?InPath "C:\UTIL",,BadPath (compare literal) ================================================== ?TIME VarName1 Retrieve the current time from the system and place in VarName1. The format of the time is hh:mm:ss xm. VarName1 should be defined as 11 long. Ex: Variable CurrTime,11 ?Time CurrTime (now contains 11:24:14 am) Page 25 PowerBatch Page 25 ================================================== ADD VarName1,VarName2 VarName1,Literal2 Add the contents of VarName2 (or Literal2) to VarName1 and place the result in VarName1. Ex: Variable YLoc,2 SetVar YLoc,6 Label LoopCtr ClearLine YLoc,Blue Add YLoc,1 Compare YLoc,11,LoopCtr This small code segment will clear lines 6 through 10 on your screen by incrementing the line number variable used by the ClearLine command. ================================================== BEEP VarName1, VarName2, VarName3 Literal1, Literal2, Literal3 Sound the system speaker with a tone of VarName1 frequency, for a length of VarName2 tenths of a second, and repeat VarName3 times. Ex: Beep 800,5,3 Beep ErrFreq,BeepLen,ErrTimes The first example sound the system speaker at a frequency of 800 hz for half a second (.5) and repeats twice for a total of 3 times. The second example will sound the system speaker at a frequency equal to the contents of the variable ErrFreq for BeepLen tenths of a second(s) for a total of ErrTimes. ================================================== Page 26 PowerBatch Page 26 BLINK Cause all text that is written to the screen to blink using the current color attributes last defined in the processing of the batch program. This command in "undone" by using NORMAL. Ex: Variable MsgClear,25." " Blink WriteAt 15,4,"Not a valid entry" Normal Wait 35 WriteAt 15,4,MsgClear Write the message "Not a valid entry" at column 15 on row 4 using the current color definition. Reset the text color to the value it contained before specifying blinking text. Wait 3.5 seconds and clear the message. ================================================== BOOT This command will cause the computer to perform a "warm" boot. This emulates the pressing of the Alt-Ctrl-Del key combination. ================================================== BOX1 VarNm1, VarNm2, VarNm3, VarNm4, VarNm5 [,VarNm6] Lit1, Lit2, Lit3, Lit4, Lit5 [,Lit6] Draw a box (frame) on the screen whose upper left co- ordinates (X,Y) are VarNm1, VarNm2, and whose lower right co_ordinates (X,Y) are VarNm3, VarNm4. Draw the box using a line in foreground color VarNm5 on background color VarNm6. The box is drawn using a single line border. Companion commands Box2, Box3, and Box4 draw boxes using a double line, a solid line, and a single line box with shadow. Ex: Variable ULX,2,5 ;upper left col value Variable ULY,2,3 ;upper left row value Variable LRX,2,75 ;lower right col value Variable LRY,2,20 ;lower right row value Variable BoxFore,2,4 ;foreground color red Variable BoxBack,2,0 ;background color black Box1 ULX, ULY, LRX, LRY, BoxFore, BoxBack Box1 5,3,75,20,7,0 Box1 5,3,75,20,112 The first example draws a box whose upper left co- Page 27 PowerBatch Page 27 ordinates are the contents of the variables ULX and ULY and whose lower left co-ordinates are the contents of the variables LRX and LRY. The box border will be the contents of BoxFore (red) on a background of BoxBack (black). The interior of the box will be unchanged (ie it is not cleared nor is the color changed). The second example draws a box whose upper left co-ordinates are 5,3 and whose lower right co- ordinates are 75,20. The box border is drawn in white on black. The third example draws a box with the same co-ordinates and uses the composite color attribute of 112 (white on black). See ClearBox command. ================================================== BREAKON Provides a capability to exit from a PowerBatch program by pressing the combination of keys (Ctrl - Break) or (Ctrl - C). The default value set at the beginning of any PowerBatch program is BreakON. To keep a user from exiting a running PowerBatch program, execute the BreakOFF command. If sections of the program are to be protected and other sections not, surround the sections with pairs of BreakON...BreakOFF commands. ================================================== BREAKOFF Disables the ability to stop a PowerBatch program by pressing the (Ctrl - Break) or (Ctrl - C) key combinations. The default value set at the beginning of any PowerBatch program is BreakON. ================================================== CENTER VarName1, VarName2 Literal1, Literal2 Center the text in VarName1 on line VarName2. Ex: Variable InpStr,25,"PowerBatch" Center "PowerBatch",2 Center InpStr,2 Both versions of this example will center the name "PowerBatch" on line 2 of the screen. ================================================== Page 28 PowerBatch Page 28 CLEAR VarName1 [,VarName2] Literal1 [,Literal2] Clear the entire screen to foreground color VarName1 and background color VarName2. Ex: Variable ColorAttr,3,112 ;define white on black Clear 4,1 Clear 112 Clear ColorAttr The first example clears the screen to red on blue. The second and third examples clear the screen to white on black. ================================================== CLEARBOX VarNm1, VarNm2, VarNm3, VarNm4, VarNm5 [,VarNm6] Lit1, Lit2, Lit3, Lit4, Lit5 [,Lit6] Clear the interior of the box whose upper left co-ordinates (X,Y) are VarNm1, VarNm2 and whose lower right co- ordinates (X,Y) are VarNm3, VarNm4. Clear the interior of the box to foreground color VarNm5 and background color VarNm6. This command clears the "inside" of the box, not the lines which describe the box. Ex: Variable ULX,2,5 ;upper left col value Variable ULY,2,3 ;upper left row value Variable LRX,2,75 ;lower right col value Variable LRY,2,20 ;lower right row value Variable BoxFore,2,4 ;foreground color red Variable BoxBack,2,0 ;background color black Box1 ULX, ULY, LRX, LRY, BoxFore, BoxBack ClearBox 5,3,75,20,112 In this example we define the upper right and lower left co-ordinates of the box as well as the colors BoxFore and BoxBack. We draw the box with a red line on a black background. The ClearBox command clears the interior of the box to white on black. ================================================== Page 29 PowerBatch Page 29 CLEARLINE VarName1, VarName2 [,VarName3] Literal1, literal2 [,Literal3] Clear the line number specified by VarName1 to a foreground color of VarName2 and a background color of VarName3. Ex: Variable Red,1,4 Variable Blue,1,1 Variable RedOnBlue,2,20 Variable CurrLine,2,12 ClearLine 12,Red,Blue ClearLine CurrLine,RedOnBlue Both examples of the ClearLine command clear line 12 on the screen to red foreground color and blue background color. ================================================== COLOR VarName1 [,VarName2] Literal1 [,Literal2] Set the default color to foreground color VarName1 and background color VarName2 or optionally set the default color attribute to VarName1. Ex: Variable RedOnBlue,2,20 Color 4,1 Color MenuClr Both examples set the default color to red on blue for any text written to the screen without specific color instructions. ================================================== Page 30 PowerBatch Page 30 COMPARE VarName1, VarName2, Label1 [,Label2] [,Label3] Literal1, Literal2, Label1 [,Label2] [,Label3] Compare the contents of VarName1 to the contents of VarName2. If VarName1 greater than VarName2 jump to the statement following Label1. If VarName1 less than VarName2 jump to the statement following Label2. If VarName1 equal VarName2 jump to the statement following Label3. If the contents of the first two operands (VarName1, VarName2, Literal1, or Literal2) are numeric then a numeric compare is performed otherwise an alphabetic compare is made. (If 19 is compared alphabetically to 2, then 2 is greater than 19; if it is compared numerically, 19 is greater than 2.) Ex: Variable InChar,1 Variable Yes,1,"Y" Variable No,1,"N" GoToXY 4,23 ReadYN "Incorrect entry...Continue [Y/N] " Compare InChar,"Y",NoIn,NoIn,YesIn Compare InChar,Yes,,,YesIn (Not Y falls through) Compare InChar,"Y",NoIn,NoIn (Y falls through) In the first example of the Compare command, variable InChar is compared to literal "Y". If InChar is greater than "Y" then the program will jump to the label NoIn; if InChar is less than "Y", the program also jumps to the label NoIn; if InChar is equal to "Y", the program will continue processing at the label named YesIn. In the second compare command, the variable InChar is compared to the variable Yes which has an assigned value of "Y". If the variable InChar contains anything but "Y", the program continues with the next instruction after the compare command (it is said to fall through); if InChar contains "Y", the program will jump to the label YesIn. In the third compare command, variable InChar is compared to the literal "Y". If the variable InChar contains "N" (ReadYN prevents any entry but Y or N) the program jumps to the label NoIn otherwise it continues with the instruction after the compare command. ================================================== Page 31 PowerBatch Page 31 CONCAT VarName1, VarName2 [,VarName3] VarName1, Literal1 [,Literal2] Concatenate the string in VarName2 with the string in VarName3 and place the result in VarName1. If VarName3 is not present then concatenate the string in VarName1 with the string in VarName2 and place the result in VarName1. Ex: Variable OutMsg,78 Variable ErrMsg," is not a valid Drive letter." Variable DriveLtr,1 WriteAt 6,17,"Enter your source drive letter " ReadUpKey DriveLtr ?DriveExist DriveLtr,DriveOK Concat OutMsg, "[19] ", DriveLtr Concat OutMsg, " is not a valid Drive letter." WriteAt 5,23,OutMsg In this example we ask the user to input a valid drive letter and verify this drive with the ?DriveExist command. If the drive is not valid we concatenate "[19]" (the error number) plus the drive letter entered by the user into the variable OutMsg. We then concatenate the error message (" is not a valid Drive letter.") onto the contents of OutMsg. The result would be something like "[19] L is not a valid Drive letter." ================================================== GOTO Label1 Jump to the statement identified as command label Label1. Ex: GoTo Error GoTo EndOfPgm ================================================== GOTOXY VarName1, VarName2 Literal1, Literal2 Move the cursor to the column (X) specified in VarName1 and row (Y) specified in VarName2. Ex: Variable CurrX,2 Variable CurrY,2 GoToXY CurrX, CurrY GoToXY 12,6 In the first example the cursor is moved to the location specified by the contents of variable CurrX and CurrY. In the second example, the cursor is moved to the location specified by two literals "12" and "6". Page 32 PowerBatch Page 32 ================================================== HALT VarName1 Literal1 Halt the batch file processing and set DOS errorlevel to VarName1. Ex: Variable Error14,2,14 ;define Error14 as "14" Halt 99 Halt Error14 In the first usage of the Halt command, the PowerBatch program is halted and the DOS errorlevel is set to 99. In the second usage the program is halted and the DOS errorlevel is set to the contents of variable Error14 ("14"). ================================================== LABEL LabelName Define a location in the list of commands that will enable execution to begin immediately following this command without necessarily having executed the command immediately prior to the Label. Jump immediately to this location in the command stream. See the discussion on labels at the beginning of this section. Ex: Label MatchErr Label EndOfPgm ================================================== LENGTH VarName1, VarName2 VarName1, Literal1 Calculate the length of the string in variable VarName2 and place the result in VarName1. Ex: Variable InString Variable StrLen WriteAt 12,14,"Enter your current directory " ReadStr InString (user enters c:\util) Length StrLen, InString (StrLen will contain 7) ================================================== LOWER VarName1 Change the alphabetic characters in VarName1 to lower case. Ex: Variable InString,25 ReadStr InString (user enters C:\UTIL) Lower InString (now contains c:\util) Page 33 PowerBatch Page 33 ================================================== MIDSTRING VarName1, VarName2, VarName3, VarName4 VarName1, Literal1, Literal2, Literal3 Extract a substring of VarName2 beginning at offset VarName3 into VarName2 for a length of VarName4 and place this substring in VarName1. Ex: Variable Path,79 WriteAt 1,2,"Enter Drive and Directory name " ReadStr Path (user enters C:\UTIL) MidString Drive,Path,1,2 (extract C: from C:\UTIL) ================================================== NORMAL Change the current color attribute(s) back to the definition prior to the execution of a BLINK or REVERSE command. Ex: Color 20 ;set default color to red on blue Blink ;changes to blinking red on blue (148) WriteAt 2,24,"Incorrect...re-enter!" Normal ;resets color to 20 Beep 800,8 Wait 35 ;pause 3.5 seconds WriteAt 2,24," " ;clear msg This is an example of a typical error routine. The color attribute is changed to blinking with the Blink command. The error message is written and the color attribute is changed back to its original value with the Normal command. The speaker is "beeped" and after a wait of 3.5 seconds, the error message is removed from the screen. ================================================== PROMPT VarName1 Literal1 Change the current value of the prompt to the value specified in VarName1 or in Literal1. Ex: Prompt "$p$g" ================================================== READKEY VarName1,VarName2 Read a single key from the keyboard and place the result in VarName1. If VarName 2 contains a "1" after reading the Page 34 PowerBatch Page 34 key from the keyboard, then a "special key" has been returned in VarName1. Special keys are function keys, Page Up/Down, cursor movement keys, etc. If you are in doubt about a particular key, run the program "KEYID" (furnished on the install disk). Each key you press will be identified as either a regular key or a special key and the value that will be returned in VarName1 when this key is pressed (remember that VarName2 will contain a "1" for special keys). Ex: Variable CharIn,1 GoToXY 1,14 Write "Enter the drive letter for output ",4,1 ReadKey CharIn Variable SpecChar,1 ;for special char indicator Variable UpArrow,1,"H" ;value for Up arrow if special Variable CtlF5,1,#98 ;value for Ctrl-F5 ReadKey CharIn,SpecChar ;compare the character in CharIn to the value of UpArrow Compare CharIn,UpArrow,NotUp,NotUp ;until we look at SpecChar, it could be UpArrow or "H" Compare SpecChar,"1",,,NotAlpha Write "You entered H" ;SpecChar not equal 1 GoTo Cont Label NotAlpha Write "You entered Up arrow" ;SpecChar equal 1 ================================================== READSTR VarName1 Read a string of characters from the keyboard until the user presses the enter key. Any number of characters may be read up to the maximum length specified for VarName1 in the Variable statement. Ex: Variable InString,12 ReadStr InString (12 chars max will be read) ================================================== READUPKEY VarName1 Read a single character from the keyboard, changing the case of any alphabetic character to upper case and place this upper case character in VarName1. Ex: ReadUpKey CharIn ================================================== Page 35 PowerBatch Page 35 READYN VarName1, VarName2 Literal1, VarName2 Write the message found in VarName1 at the current cursor location and wait for a single key to be entered from the keyboard. Force the user to enter either a "Y" or "N" and place the upper case "Y" or "N" in VarName2. Ex: Variable Msg4,35,"Invalid name...Continue [Y/N] " ReadYN "Invalid name...Continue [Y/N] ",CharIn ReadYN Msg4,CharIn In both usages of the ReadYN command, the message "Invalid filename...Continue [Y/N] " will be displayed and the program will wait for a response from the user. If the user enters any characters other than "Y", "y", "N", or "n" the system speaker will sound and the user is prompted again for input. At the completion of this command, the variable CharIn will contain either "Y" or "N" (always upper case). ================================================== REVERSE Change the text attributes to "reverse video". This is accomplished by swapping the foreground and background attributes. This command is "undone" by using NORMAL. Ex: Color 20 ;red on black Reverse ;color is changed to black on red WriteAt 1,15,"Press Escape To Continue" Normal ;color is now red on black ================================================== SETENV VarName1, VarName2 Literal1, Literal2 Set the value of the environment variable specified in VarName1 or Literal1 to the value specified in VarName2 or Literal2. Ex: Variable VarName,7,"MONITOR" Variable VarValue,5,"color" SetEnv VarName, VarValue SetEnv "Monitor","color" ================================================== Page 36 PowerBatch Page 36 SETPATH VarName1 Literal1 Set the current path to the value specified in VarName1 or the value specified in Literal1. Ex: Variable NewPath,40,"d:\;c:\util\exec;c:\wp\letters;c:\dos" SetPath NewPath SetPath "d:\;c:\;" ================================================== SETVAR VarName1, VarName2 VarName1, Literal1 Set the value of VarName1 to the contents of VarName2. Ex: Variable ErrCode,3 Variable FileName,79 SetVar ErrCode,99 SetVar FileName,"C:\CONFIG.SYS" In the first usage of the SetVar command, the variable ErrCode is set to "99" and the second usage sets the variable FileName to "C:\CONFIG.SYS" ================================================== SUBTRACT VarName1,VarName2 VarName1,Literal2 Subtract the contents of VarName2 (or Literal2) from the contents of VarName1 and place the result in Varname 1. ================================================== UPPER VarName1 Change the alphabetic characters in VarName1 to upper case. Ex: Variable InString,25 WriteAt 14,25,"Enter your directory name " ReadStr InString (user enters c:\util) Upper InString (changed to C:\UTIL) ?InPath InString,GoodDir (path is always upper case) In this example, the user is prompted for a path name to be entered. The path name is to be compared to the system path for validity. Since the contents of the system path are always in upper case, we change the InString variable to upper case prior to comparison. Page 37 PowerBatch Page 37 ================================================== VARIABLE VariableName, MaxLength [,InitialValue] Define a variable to PowerBatch. All variables used in a PowerBatch program must have been defined with a VARIABLE command. VariableName is the name which you give to this variable and the means by which you refer to the variable in other PowerBatch statements. This variable may contain any number of characters up to MaxLength and is set to the initial value of InitialValue. The initial value of a variable may be assigned by means of the decimal value of the ascii character. To define the initial value of a variable using the ascii value, precede the value with # (see example below). See the discussion on variables at the beginning of this section. Command line parameters passed to a compiled PowerBatch program must be defined as variables. Up to 16 command line variables may be passed to a compiled PowerBatch program and they are defined as CLP%1..CLP%16. See the example MOVE1 or MOVE2. Ex: Variable DayOfWeek,9 Variable ErrMsg1,25,"Invalid directory name." Variable InString,80,"" Variable PauseTime,2,50 Variable RightArrow,1,#26 Variable DblLine,5,#205#205#205#205#205 Variable CLP%1,12 (command line parameter %1) ================================================== WAIT VarName1 Literal1 Cause the execution of a PowerBatch program to pause for VarName1 tenths of a second(s). Ex: Wait 5 (pause half a second) Wait PauseTime (pause 5 seconds) ================================================== Page 38 PowerBatch Page 38 WRITE VarName1, VarName2 [,VarName3] Literal1, Literal2 [,Literal3] Write the string contained in VarName1 at the current cursor location using color attributes foreground VarName2 and background VarName3. In the absence of VarName2 and VarName3 use the current color attributes. The string is not followed by a carriage return, line feed pair (ie the cursor is not moved to the first position of the next line). SEE SPECIAL NOTE BELOW ON IMBEDDED COLOR COMMANDS. Ex: Write "Enter your password ",0,7 Variable ErrMsg1,25,"Invalid directory name." Variable ErrClr,3,112 Write ErrMsg1,ErrClr ================================================== WRITEAT VarName1, VarName2, VarName3 [,VarName4] [,VarName5] Literal1, Literal2, Literal3 [,Literal4] [,Literal5] Write the string contained in VarName3 at column (X) contained in VarName1 and row (Y) contained in VarName2 using the foreground color attribute contained in VarName4 and the background color attribute contained in VarName5. In the absence of VarName4 and VarName5, use the current color attributes. The string is not followed by a carriage return, line feed pair (ie the cursor is not moved to the first position of the next line). SEE SPECIAL NOTE BELOW ON IMBEDDED COLOR COMMANDS. Ex: Variable TitleClr,3,112 Variable CurrX,2 Variable CurrY,2 Variable CompName,25,"The ABC Company" WriteAt 15,3,"The ABC Company",TitleClr WriteAt CurrX,CurrY,CompName In the first usage of the WriteAt command the literal "The ABC Company" is written at column 15, row 3. In the second usage, the contents of the variable CompName ("The ABC Company") is written at the column location specified by the contents of variable CurrX and at the row location specified by the contents of variable CurrY. ================================================== Page 39 PowerBatch Page 39 WRITELINE VarName1 [,VarName2] Write the string contained in VarName1 beginning in location 1 of the line number specified in VarName2. Follow the string with a carriage return line feed pair (ie move the cursor to the first position of the next line). In the absence of VarName2 write the string at the current cursor location. SEE SPECIAL NOTE BELOW ON IMBEDDED COLOR COMMANDS. Ex: WriteLine "Please read these instructions ",7 WriteLine Msg5 In the first usage of WriteLine the message "Please read these instructions " is written beginning in column 1 of row 7. In the second usage the contents of the variable Msg5 is written beginning at the current cursor location. In both cases a carriage return, line feed (position cursor at the first position of the next line) is written. Page 40 PowerBatch Page 40 IMBEDDED COLOR COMMANDS A literal or a variable may be defined which has color commands imbedded in the text of the literal allowing you to change the color in the middle of the string to be printed. If you were creating a tutorial and wanted a menu at the bottom of the screen that gave the user several command choices and you wanted this menu to have the first character of each command in reverse video, PowerBatch provides a means to accomplish this easily. Suppose the command line is: Next Previous Load ........ and the N, P, and L were to be in reverse video you would define the variable (or literal) as: Variable Cmd,75,"@112N@007ext @112P@007revious @112L@007oad" IN THIS EXAMPLE THE @ REPRESENTS CTRL-A BECAUSE YOUR PRINTER WILL NOT PRINT A CTRL-A! The syntax for imbedded color commands is Ctrl-A followed by the THREE digit color attribute. Thus @112 means change the color to color 112 and continue printing in this color until another change is made. Further examining the line...@112N@007ext means change to color 112, print N, change to color 007, print ext (Next). The ascii value of Ctrl-A is 001. Most text editors will allow you to enter an ascii character by entering the actual ascii value by pressing the Alt key and entering the ascii value on the numeric keypad (not the numbers above the character keyboard). Thus entering Ctrl-A becomes as simple as pressing Alt-1. See Appendix B for a complete list of composite color attributes. Page 41 PowerBatch Page 41 Command Summary ?COLOR Var1, Var2, Var3 ?CURRDIR Var1, Var2 ?DATE Var1, Var2, Var3, Var4 ?DIREXIST Var1, Lab1 [,Lab2] or Lit1, Lab1 [,Lab2] ?DISKSPACE Var1, Var2, Var3 ?DRIVEEXIST Var1, Lab1 [,Lab2] or Lit1, Lab1 [,Lab2] ?ENVSTR Var1, Var2 or Lit1, Var2 ?FILEEXIST Var1, Lab1 [,Lab2] or Lit1, Lab1 [,Lab2] ?INPATH Var1, Lab1 [,Lab2] or Lit1, Lab1 [,Lab2] ?TIME Var1 ADD Var1,Var2 or Var1, Lit2 BEEP Var1, Var2, Var3 or Lit1, Lit2, Lit3 BLINK BOOT BOX1 Var1, Var2, Var3, Var4, Var5 [,V6] or Lit1, Lit2, Lit3, Lit4, Lit5, [,Lit6] BREAKON BREAKOFF CENTER Var1, Var2 or Lit1, Lit2 CLEAR Var1 [,Var2] or Lit1 [,Lit2] CLEARBOX Var1, Var2, Var3, Var4, Var5 [,V6] or Lit1, Lit2, Lit3, Lit4, Lit5 [,Lit6] CLEARLINE Var1, Var2 [,Var3] or Lit1, Lit2, Lit3 COLOR Var1 [,Var2] or Lit1 [,Lit2] COMPARE Var1, Var2, Lab1 [,Lab2] [,Lab3] or Lit1, Lit2, Lab1 [,Lab2] [,Lab3] CONCAT Var1, Var2 [,Var3] or Var1, Lit2 [,Lit3] GOTO Lab1 HALT Var1 or Lit1 LENGTH Var1, Var2 or Var1, Lit1 LOWER Var1 MIDSTRING Var1, Var2, Var3, Var4 or Var1, Var2, Lit1, Lit2 NORMAL PROMPT Var1 or Lit1 READKEY Var1,Var2 READSTR Var1 READUPKEY Var1 READYN Var1, Var2 or Lit1, Var1 REVERSE SETENV Var1, Var2 or Lit1, Lit2 SETPATH Var1 or Lit1 SETVAR Var1, Var2 or Var1, Lit1 SUBTRACT Var1, Var2 or Var1, Lit1 UPPER Var1 VARIABLE VariableName, MaxLength [,InitialValue] WAIT Var1 or Lit1 WRITE Var1, Var2 [,Var3] or Lit1, Lit2 [,Lit2] WRITEAT Var1, Var2, Var3 [,Var4] [,Var5] or Lit1, Lit2, Lit3, [,Lit4] [,Lit5] WRITELINE Var1 [,Var2] or Lit1 [,Lit2] Page 42 PowerBatch Page 42 ERRORLEVEL Predefined variable containing the value of the exit code set by the previous program or command. DOSERROR Predefined variable containing the last set value of the operating system error code. Page 43 PowerBatch Page 43 Compilation Errors Compilation errors are printed on the screen and also written in a file named POWERBAT.ERR (If you have a split screen editor, view the source in one screen part and the errors in the other part). If the source line is available, the source line is printed above the error preceded by the line number count. Source lines are not available during the second pass of the compiler which may generate "Label not defined" and "Variable not defined" errors. "Not a valid command" - This error is generated when the first word on the command line is not a PowerBatch command and contains more than 8 characters. Example: 13 Directory name checked here. [DIRECTORY] Not a valid command Probably should be ;Directory name checked here "Missing variable" - A command contains less than the required number of operands. Example: 21 ?Color ForeColor,BackColor [] Missing variable Variable for the composite color byte is missing. "Expected a variable Name" - A string was found in an operand that may contain only a variable name. Example: 10 ?Time "Current Time" [Current Time] Expected a variable name The current time may only be placed in a variable. "Quoted literal not terminated" - A single quote was encountered within a source line. Example: 9 Center "Move Command,5 [] Quoted literal not terminated Closing quote should precede comma. Page 44 PowerBatch Page 44 "Invalid max length specified" - The second operand of a variable definition should specify the maximum length of the variable. The value found was not numeric. Example: 3 Variable CompName,"The ABC Company" [The ABC Company] Invalid max length specified "Variable not defined" - A reference to a variable was made in the source file but the variable was not defined with the Variable command. Example: [CURRDATE] Variable not defined "Duplicate variable" - The same variable name has appeared 2 or more times in a Variable definition statement. Example: 7 Variable CompName,25 [COMPNAME] Duplicate variable "Duplicate label" - The same label name has appeared 2 or more times in a Label definition statement. Example: 16 Label Step2 [STEP2] Duplicate label "Invalid hex definition in variable" - A variable definition contained a # not enclosed in quotes signifying a value definition by ascii value. The characters following this # were not numeric or did not equate to an ascii character. Example: Variable Return,2,#J#219 #J is not valid "External command >" - This is not an error message, but is a check to alert you to each command found in a PowerBatch source file that will be treated as an external command. External commands are DOS intrinsic commands, .COM, and .EXE commands or programs (even PowerBatch compiled programs) and .BAT (standard DOS batch files) that are to be executed by PowerBatch. Example: External command > 12 DIR (DOS directory command) External command > 29 MYPROG (Executable module MYPROG) Page 45 PowerBatch Page 45 Removing PowerBatch From Your System While we believe that PowerBatch is a batch compiler that everyone should own, we recognize that there are some who feel it is not a program they will use on a regular basis. For those of you in that minority, we have provided a program to easily remove all PowerBatch modules from your system. To remove all modules from your system that were supplied on the PowerBatch install disk, enter DELETEPB <enter> You will be asked if you wish to remove all PowerBatch modules from the currently logged disk. If this is the correct disk, enter Y. If it is not the correct disk, enter N and the program will terminate. (You should move to the disk containing the PowerBatch modules.) You will next be asked if you wish to confirm each deletion. If you reply (Y)es, each time a PowerBatch module is found, you will be asked if you wish to delete this module. If you reply (N)o, the modules will be deleted as they are found without your intervention. Page 46 PowerBatch Page 46 Examples The source for several examples is contained on your installation disk. You may print these examples by entering: COPY DEMO1.PWR LPT1 These examples may be compiled using the POWERMAK command by entering: POWERMAK DEMO1 <enter> Page 47 PowerBatch Page 47 Appendix A Dealer and Site License Information Site License Pricing A site license is issued when you wish to receive one master copy of PowerBatch and duplication is controlled by you. If you obtain a site license, support will be provided to one designated contact within your company. Quantity Price 4 - 10 $18 per copy 11 - 50 $15 per copy 51 - 100 $900 101 - 250 $1750 251 - 1000 $5000 Contact CSD, Inc. for site license pricing for usage above 1000 Dealer Pricing Dealer pricing is obtained by ordering multiple copies of PowerBatch on one order. Multiple complete copies of PowerBatch are delivered and multiple registrations accepted. Support is provided to each registrant. Quantity Price 2 - 5 $23 per copy 6 - 10 $21 per copy 11 - 25 $19 per copy 26 - 50 $17.50 per copy 51 - 100 $15 per copy Contact CSD, Inc. for pricing on quantities in excess of 100 Page 48 PowerBatch Page 48 Appendix B Composite Color Values Color Names ----------- Name Value Name Value Name Value --------- --- ---------- --- ---------- --- Black 0 Brown 6 Lt.Cyan 11 Blue 1 Lt.Gray 7 Lt.Red 12 Green 2 Dk.Gray 8 Lt.Magenta 13 Cyan 3 Lt.Blue 9 Yellow 14 Red 4 Lt.Green 10 White 15 Magenta 5 Foreground Colors (0 - 15) Normal (non-blinking) Colors Bkg0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 --- --- --- --- --- --- ------ --- --- --- --- --- --- ------ 0 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 1 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 2 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 3 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 4 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 5 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 6 96 97 98 99 100 101 102103 104 105 106 107 108 109 110111 7 112 113 114 115 116 117 118119 120 121 122 123 124 125 126127 Colors Which Blink 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 --- --- --- --- --- --- ------ --- --- --- --- --- --- ------ 0 128 129 130 131 132 133 134135 136 137 138 139 140 141 142143 1 144 145 146 147 148 149 150151 152 153 154 155 156 157 158159 2 160 161 162 163 164 165 166167 168 169 170 171 172 173 174175 3 176 177 178 179 180 181 182183 184 185 186 187 188 189 190191 4 192 193 194 195 196 197 198199 200 201 202 203 204 205 206207 5 208 209 210 211 212 213 214215 216 217 218 219 220 221 222223 6 224 225 226 227 228 229 230231 232 233 234 235 236 237 238239 7 240 241 242 243 244 245 246247 248 249 250 251 252 253 254255 To find the composite color attribute for a particular color combination, select the background color (0 - 7) and then go across under the foreground color (0 - 15) colums until you are under the selected foreground color column. The number at the intersection of these two color combinations is the composite color. For example if you wish to have yellow letters on a blue background, go down the background lines to the blue line (color = 1) and go across to the yellow column (color = 14). At the intersection of these two lines and columns read 30 for the composite color. Page 49 PowerBatch Page 49 Index ASP 1 ?TIME 23 Box 25 ADD 24 Case BEEP 24 lower 31 BLINK 25 upper 33, 35 BOOT 25 Color attribute 18, 19, 32 BOX 25 Command line parameters 36 BREAKOFF 26 Command Summary 40 BREAKON 26 Command Syntax 19 CENTER 26 Comments 12 CLEAR 27 Compare CLEARBOX 27 alphabetic 29 CLEARLINE 27 numeric 29 COLOR 28 Compilation Errors 42 COMPARE 28 Concatenate 30 CONCAT 30 Concept Of Operation 7 GOTO 30 Copyright 1 GOTOXY 30 Ctrl - Break 26 HALT 31 Current date 20 LABEL 31 Current time 23 LENGTH 31 Cursor 30 LOWER 31 Directory 21 MIDSTRING 32 Disk capacity 21 NORMAL 32 Disk free space 21 PROMPT 32 DOS errorlevel 31 READKEY 32 DOS search path 23 READSTR 33 DOSERROR 13, 16 READUPKEY 33 Environment variable 22 READYN 34 ERRORLEVEL 13, 16, 31 REVERSE 34 External command 15, 43 SETENV 34 Field length SETPATH 35 maximum 33, 36 SETVAR 35 File exists 23 SUBTRACT 35 Frame 25 UPPER 35 Installation 9 VARIABLE 36 Interior of a box 27 WAIT 36 Introduction 1 WRITE 37 Literals 12, 13 WRITEAT 37 Pause 36 WRITELINE 37 POWERBAT.ERR 42 POWERMAK 11 PowerBatch Commands 12 Registration 1 ?COLOR 19 Registration Fees 5 ?CURRDIR 20 Removing PowerBatch From Your ?DATE 20 System 44 ?DIREXIST 21 Screen clear 27 ?DISKSPACE 21 Shareware 1 ?DRIVEEXIST 22 Software Support 6 ?ENVSTR 22 String length 31 ?FILEEXIST 23 Substring 32 ?INPATH 23 System speaker 24 Page 50 PowerBatch Page 50 Valid drive 22 Value initial 36 Variable 12 value 35 Variable map 11 Warranty 5 What You Get 5